<!doctype html public "-//w3c//dtd html 4.0 transitional//en">


<!-- WARNING! This file is generated. -->
<!-- To alter documentation, edit files in src directory -->


<html><head>
<title>Administrative Topics</title>
<link rel="stylesheet" href="utplsql.css" content="text/css">
<meta name="keywords" content="utPLSQL, PL\SQL, Unit Testing, Framework, Oracle"/>
<meta name="description" content="Unit Testing PL\SQL"/>
<meta name="title" content="Administrative Topics"/>
<meta name="author" content="Steven Feuerstein, Chris Rimmer, Patrick Barel"/>
<meta name="copyright" content="(C) 2000-2005 Steven Feuerstein, Chris Rimmer, Patrick Barel"/>
</head><body>
<div class="purple_bar"><a href="index.html"><img src="utplsql.jpg" border=0></a></div>
<p>[ <A href="index.html">Home</A>
 | <A href="started.html">Getting Started</A>
 | <A href="buildpack.html">Build Test Packages</A>
 | <A href="examples.html">Examples</A>
 | <A href="userguide.html">User Guide</A>
 | <A href="release.html">Release Notes</A>
 | <A href="map.html">Document Map</A> ]</p>
<p><A href="fourstep.html">&lt; Previous Section: The Four Step Program to using utPLSQL</A> | <A href="buildpack.html">Next Section: Build Test Packages &gt;</A></p>
<!-- Begin utPLSQL Body -->
<!-- $Id: admin.html,v 1.5 2003/06/18 13:02:28 chrisrimmer Exp $ -->
<h1>
Administrative Topics</h1>

<h3>
<a href="admin.html">Configuring UTL_FILE</a></h3>

<h3>
<a href="#Project_Team">Join the Project Team</a></h3>

<h3>
<a href="#Reporting">Reporting Bugs and Enhancement Requests</a></h3>

<h2>
<a name="Admin"></a>Administrative Topics</h2>

<h3>
<a name="UTL_FILE"></a>Configuring UTL_FILE</h3>
If you want utPLSQL to automatically recompile your test packages, you
will need to make sure that UTL_FILE is enabled in your database (this
allows you to read/write operating system files). The database initialization
parameter file (aka, the "init.ora" file) must have at least one utl_file_dir
parameter in it for this to work. Here is some background and guidelines
for working with UTL_FILE:
<p>UTL_FILE lets you read and write files accessible from the server on
which your database is running. So, theoretically, you could use UTL_FILE
to write right over your tablespace data files, control files and so on.
That is, of course, a very bad idea. Server security requires the ability
to place restrictions on where you can read and write your files.
<p>UTL_FILE implements this security by limiting access to files that reside
in one of the directories specified in the init.ora file (parameter initialization
file) for the database instance on which UTL_FILE is running.
<p>When you call UTL_FILE.FOPEN to open a file, you must specify both the
location and the name of the file, in separate arguments. This file location
is then checked against the list of accessible directories.
<p>The format of the parameter for file access in the init.ora file is:
<pre>
utl_file_dir = &lt;directory&gt;
</pre>
Include a parameter for utl_file_dir for each directory you want to make
accessible for UTL_FILE operations. The following entries, for example,
enable four different directories in Unix:
<pre>
utl_file_dir = /tmp
utl_file_dir = /ora_apps/hr/time_reporting
utl_file_dir = /ora_apps/hr/time_reporting/log
utl_file_dir = /users/test_area
</pre>
To bypass server security and allow read/write access to all directories,
you can use this special syntax:
<pre>
utl_file_dir = *
</pre>
You should not use this option on production systems. In a development
system, this entry certainly makes it easier for developers to get up and
running on UTL_FILE and test their code. You should, however, only allow
access to a few specific directories when you move the application to production.
<h4>Some observations on working with and setting up accessible directories
with UTL_FILE:</h4>
<p>Access is not recursive through subdirectories. If the following lines
were in your init.ora file, for example,
<pre>
utl_file_dir = c:\group\dev1
utl_file_dir = c:\group\prod\oe
utl_file_dir = c:\group\prod\ar
</pre>
then you would not be able to open a file in the c:\group\prod\oe\reports
subdirectory.
<p>Do not include the following entry in Unix systems:
<pre>
utl_file_dir = .
</pre>
This would allow you to read/write on the current directory in the operating
system.
<p>Do not enclose the directory names within single or double quotes.
<p>In the UNIX environment, a file created by UTL_FILE.FOPEN has as its
owner the shadow process running the Oracle instance. This is usually the
oracle owner. If you try to access these files outside of UTL_FILE, you
will need to have the correct privileges (or be logged in as oracle) to
access or change these files.
<p>You should not end your directory name with a delimiter, such as the
forward slash in Unix. The following specification of a directory will
result in problems when trying to read from or write to the directory:
<pre>
utl_file_dir = /tmp/orafiles/
</pre>
After you modify your parameter initialization file, you will need to stop
and then restart your database instance.
<h4>Test UTL_FILE Access</h4>
<p>If you have never before used or relied on UTL_FILE, you should write
a simple test to verify that UTL_FILE is now working. You can use the code
shown below (after changing your directory names and names for existing
and new files) to make sure you've got it running properly.
<pre> 
SET SERVEROUTPUT ON
DECLARE
   fid UTL_FILE.FILE_TYPE;
   v VARCHAR2(32767);
   PROCEDURE recNgo (str IN VARCHAR2)
   IS
   BEGIN
      DBMS_OUTPUT.PUT_LINE ('UTL_FILE error ' || str);

      UTL_FILE.FCLOSE (fid);
   END;
BEGIN
   /* Change the directory name to one to which you at least 
   || THINK you have read/write access.
   */
   fid := UTL_FILE.FOPEN ('e:\demo', 'existing_file', 'R');
   UTL_FILE.GET_LINE (fid, v);
   dbms_output.put_line (v);
   UTL_FILE.FCLOSE (fid);

   fid := UTL_FILE.FOPEN ('e:\demo', 'new_file', 'W');
   UTL_FILE.PUT_LINE (fid, v);
   UTL_FILE.FCLOSE (fid);
EXCEPTION
   WHEN UTL_FILE.INVALID_PATH
    THEN recNgo ('invalid_path');
   WHEN UTL_FILE.INVALID_MODE
    THEN recNgo ('invalid_mode');
   WHEN UTL_FILE.INVALID_FILEHANDLE
    THEN recNgo ('invalid_filehandle');
   WHEN UTL_FILE.INVALID_OPERATION
    THEN recNgo ('invalid_operation');
   WHEN UTL_FILE.READ_ERROR
    THEN recNgo ('read_error');
   WHEN UTL_FILE.WRITE_ERROR
    THEN recNgo ('write_error');
   WHEN UTL_FILE.INTERNAL_ERROR
    THEN recNgo ('internal_error');
END;
/</pre>
If an error occurs, it will be displayed on your screen (note: the "set
serveroutput on" is not required for UTL_FILE to work, but simply to display
any errors which might occur).
<br> 
<h3>
<a name="Project_Team"></a>Join the utPLSQL Project Team</h3>

To take part in the utPLSQL project, first please join
the utPLSQL Forum. Go to 
<a href="http://utplsql.oracledeveloper.nl">http://utplsql.oracledeveloper.nl</a>
and join in the discussions. Once you are up to speed on the project, you
can go to the <a href="http://utplsql.sourceforge.net">SourceForge site</a>, choose a task and begin
to contribute.

<h3>
<a name="Reporting"></a>Reporting Bugs and Enhancement Requests</h3>

To identify the version of utPLSQL you are running,
you can execute the following program in SQL*Plus:

<pre>SQL&gt; set serveroutput on
SQL&gt; exec dbms_output.put_line (utPLSQL.version)</pre>

You can also look inside the utPLSQL package (utPLSQL.pkb)
and check the value of the g_version private variable.

<!-- End utPLSQL Body -->
<p><A href="fourstep.html">&lt; Previous Section: The Four Step Program to using utPLSQL</A> | <A href="buildpack.html">Next Section: Build Test Packages &gt;</A></p>
<div class="purple_bar"><a href="index.html"><img src="utplsql.jpg" border=0></a></div>
<p class="copyright">Copyright (C) 2000-2005 <A href="mailto:steven@stevenfeuerstein.com">Steven Feuerstein<A>, <A href="mailto:c@24.org.uk">Chris Rimmer<A>, <A href="mailto:pbarel@vda.nl">Patrick Barel<A> All rights reserved</p>
</body></html>